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Summary 
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¢ SPICE provides means to create CK files, either by packaging 
orientation computed by others, or by first computing orientation 
within SPICE and then packaging it in a CK file 


— Packaging of already existing orientation data can be done in two ways: 


» Use SPICE CK writer routines by calling them from within your own SPICE- 
based application 


» Convert a text file containing orientation data to a CK using the Toolkit’s 
msopck program 


— Computing as well as packaging orientation can be done in two ways: 


» Use SPICE geometry routines and CK writer routines by calling them from 
within your own SPICE-based application 


¢ Constructing orientation using SPICE routines is not discussed here 


» Convert orientation rules and schedules to a CK using the prediCkt 
program available from the NAIF website 
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CK Writer Routines 
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¢ The SPICE toolkit provides the following CK writer routines for 
the FORTRAN, C, IDL and MATLAB toolkits, respectively: 
— For Type 1 CK 
» CKW01 / ckw01_c/ cspice_ckw01 
— For Type 2 CK 
» CKW02 / ckw02_c/ cspice_ckw02 
— For Type 3 CK 
» CKWO03 / ckw03_c/ cspice_ckw03 
For Type 4 CK 
» CKW04B, CKW04A, CKWO4E (no CSPICE, Icy, or Mice wrappers) 
— For Type 5 CK 
» CKW05 / ckw05_c (no Icy or Mice wrapper) 
For Type 6 CK 
» CKWO06 (no CSPICE, Icy or Mice wrappers) 


¢ Only the Type 3 writer is discussed in this tutorial 
— Writers for Types 1 and 2 have very similar interfaces 
— Types 4, 5 and 6 are are not commonly used 
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NAIE> Type 3 Writer Example - 1 
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¢ The following C-language code fragment 
illustrates the creation of a Type 3 C-kernel 
having a single segment. 


ckopn_c ( filename, “my-ckernel”, 0, &handle ) ; 
/* 
Insert code that properly constructs the 
sclkdp, quats, avvs, and starts arrays. 
“7 
ckw03 c ( handle, begtim, endtim, inst, 
“ref”, avfilag, “segid”, nrec, 
sclkdp, quats, avvs, nints, starts ); 


ckcls c ( handle ); 
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NAIE> Type 3 Writer Example - 2 
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handle - file handle for the newly created C-kernel. 


begtim, endtim - start and stop times in SCLK 
ticks for the segment. 

inst - ID code for the instrument for which the C- 
kernel is being made. 

ref -name of the base reference frame. Must be 
one known to SPICE during your program execution. 
avflag - a SpiceBoolean indicating whether or not 
to include angular velocity in the segment. 


segid -a string identifying the segment. It must be 
no more than 40 characters in length. 
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NAIE> Type 3 Writer Example - 3 
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¢ nrec - number of records in sclkdp, quats, and avvs. 


sclkdp - monotonically increasing list of times, given 
in SCLK ticks, that identify when quats and avvs were 
sampled or calculated. 


quats -a list of SPICE quaternions that rotate vectors 
from the base frame specified by the ref argument to 
the inst frame. 


avvs - angular rate vectors given in the base frame 
specified by the ref argument. 

nints - number of entries in starts. 

starts -a list of SCLK ticks indicating the start of 


interpolation intervals. They must correspond to 
entries in sclkdp. 
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Type 3 writer - Making Up Rates 
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¢ One of the easiest ways to make up angular rates 
is to assume a constant rotation rate between 
subsequent quaternions: 
for (k=0; k<(nrec-1); k++ ) { 
q2m_c ( quats[k][0], init rot ); 
q2m_c ( quats[k+1][0], final_rot ); 
mtxm_c ( final rot, init _rot, rotmat ); 
raxisa_c ( rotmat, axis, &angle ); 
sct2e c ( scid, sclkdp[k], &init_et ); 
sct2e c ( scid, sclkdp[k+1], &final_et ); 
vscl_c ( angle/(final_et-init et), axis, 
&avvs[k][0] ); } 


¢ Then copy the (nrec-1) value of avvs into the last 
element of avvs. 


Making a CK File continued on next page 


NAIE>Type 3 Writer - Making Up Rates (2) 


¢ Constructing angular rates in this fashion 
assumes that no more than one 180-degree 
rotation has occurred between adjacent 
quaternions. 
— raxisa_c chooses the smallest angle that performs the 
rotation encapsulated in the input matrix. 


¢ Other techniques exist, including differentiating 
quaternions. Care must be exercised when taking 
that approach. 
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NAIE> MSOPCK 
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¢ msopck makes CK files from orientation data provided ina 
time- tagged, space-delimited table in text format 


¢ msopck can process quaternions (SPICE and non-SPICE 
styles), Euler angles, or rotation matrices, tagged with UTC, 
SCLK, or ET time tags 


¢ msopck requires all program directives to be provided ina 
setup file that follows the SPICE text kernel syntax 


¢ msopck has a simple command line interface with the following 
usage 


msopck setup file input data file output_ck file 


¢ If the specified output CK already exists, new segment(s) are 
appended to it 
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Supporting 


Kernels/Files 


Output CK 


Specifications 


Input data 


Specifications 


Optional and 
conditional 


keywords are 
shown in green 
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MSOPCK 


List of Setup File Keywords 
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LSK_FILE NAME 
SCLK_ FILE NAME 

FRAMES FILE NAME 
COMMENTS FILE NAME 
PRODUCER _ID 
INTERNAL FILE NAME 
CK_SEGMENT_ID 

CK_TYPE 

INSTRUMENT_ID 
REFERENCE FRAME NAME 
MAXIMUM VALID INTERVAL 
INPUT TIME TYPE 

TIME CORRECTION 

INPUT DATA TYPE 


QUATERNION NORM ERROR 
EULER_ANGLE_UNITS 
EULER _ROTATIONS ORDER 
EULER ROTATIONS TYPE 
ANGULAR_RATE PRESENT 
ANGULAR_RATE FRAME 
ANGULAR_RATE THRESHOLD 
OFFSET_ROTATION ANGLES 
OFFSET ROTATION AXES 
OFFSET_ROTATION UNITS 
DOWN_SAMPLE TOLERANCE 
INCLUDE INTERVAL TABLE 
CHECK TIME ORDER 


'LSK file' 

"SCLK file’ (or MAKE FAKE SCLK=‘new SCLK file’ 
‘FRAMES file' 

'file containing comments' 

‘producer group/person name' 

‘internal file name string' 

"segment ID string' 

1, 2, or 3 

CK ID 

‘reference frame name' 


= interval length, seconds 


"SCLK', 'UTC', 'TICKS', 'DPSCLK', or 'ET' 
bias to be applied to input times, seconds 
"MSOP QUATERNIONS', 'SPICE QUATERNIONS', 
"EULER ANGLES', or 'MATRICES' 


= maximum normalization error 


"DEGREES' or 'RADIANS' 

( ’axis3’, ‘axis2’, 'axisl' ) 

"BODY' or 'SPACE' 

'YES', 'NO', 'MAKE UP', 'MAKE UP/NO AVERAGING' 
"REFERENCE' or 'INSTRUMENT' 

( max X rate, max Y rate, max Z rate ) 
( angle3, angle2, anglel ) 

( ’axis3’, ‘axis2’, 'axisl' ) 
"DEGREES' or 'RADIANS’ 

down sampling tolerance, radians 

'YES' or 'NO' (default 'YES') 

"YES' or 'NO' (default 'NO') 


MSOPCK - Input Details (1) 
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Four Examples 


INPUT DATA TYPE 


Input file: 


INPUT DATA TYPE 


Input file: 


INPUT DATA TYPE 


Input file: 


INPUT DATA TYPE 


Input file: 
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= 'SPICE QUATERNIONS' 


[TIME2] QOCOS QOSINI] 


INI 


QSIN2 OSIN3 [ARX ARY ARZ ] 


QS 


IN2 QSIN3 [ARX ARY ARZ ] 


-OS 


IN2 


-QSIN2 


-QSIN3 QCOS [ARX ARY ARZ ] 


-QSIN3 QCOS [ARX ARY ARZ ] 


Il 
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Fi 
py) 
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Fi 
n 


[TIME2] ANG3 ANG2 ANGI 


[ARX ARY ARZ ] 


[ARX ARY ARZ ] 


M33 [ARX ARY ARZ ] 


M33 [ARX ARY ARZ ] 
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MSOPCK - Input Details (2) 
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¢ Quaternions 
— INPUT_DATA_TYPE = ‘SPICE QUATERNIONS’ indicates the quaternions being 
used follow the SPICE formation rules(*) 


— INPUT_DATA_TYPE = ‘MSOP QUATERNIONS’ indicates the quaternions being 
used follow the traditional AACS formation rules(*) 


» Normally quaternions that come in telemetry are of this type 


— QUATERNION_NORM_ERROR keyword may be used to identify and filter out 
input records with quaternions that are not unit vectors 


» It is set to a tolerance for comparing the norm of the input quaternion 
with 1 


¢ Euler angles 
— All three angles must be provided 
— For the angles provided on the input as 
TIME1 [TIME2] ANG3 ANG2 ANG1 [ ARX ARY ARZ ] 
and rotation axes specified in the setup as 
EULER ROTATIONS ORDER = ( ’axis3’, ‘'axis2’, 'axisl' ) 
the matrix rotating vectors from base to the structure frame is computed as 
Vinst = [ANG3]axis3 * [ANG2]axis2 * [ANGl]axisl * Vref 
— Angles can be provided in degrees or radians 
(*) NAIF prepared a “white paper” explaining differences between various quaternion styles: 
Making a CK File https://naif.jpl.nasa.gov/pub/naif/misc/Quaternion_White_Paper/Quaternions_White_Paper.pdf 12 


MSOPCK - Input Details (3) 
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¢ Angular rates are an optional input. Their presence or absence 
must be indicated using the ANGULAR_RATE_PRESENT 


keyword 

— If angular rates are provided (ANGULAR_RATE_PRESENT = ‘YES’), they 
must be in the form of a 3D vector expressed either in the base frame (less 
common) or instrument frame (more common) 

» The ANGULAR_RATE_FRAME keyword must be set to indicate which of 
the two is used 

— If angular rates are not provided, the program can either make a CK without 
rates (ANGULAR_RATE_PRESENT = ‘NO’), or try to compute rates from the 
orientation data by using a uniform rotation algorithm implemented in Type 
3 CKs, either with averaging (ANGULAR_RATE_PRESENT = ‘MAKE UP’) or 
without averaging (ANGULAR_RATE_PRESENT = ‘MAKE UP/NO 
AVERAGING’) of the rates computed for adjacent orientation data points 

— ANGULAR_RATE_THRESHOLD may be used to identify and filter out input 
records with angular rate components that are too large to be real 


¢ Input data can be tagged with UTC, SCLK string, SCLK ticks or 
ET, as specified using the INPUT_TIME_TYPE keyword 


— Time tags must not have embedded spaces 
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MSOPCK - Output Details (1) 
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¢ msopck can generate Type 1, 2, or 3 CKs 


— Type 1 is rarely used - only in cases when the input contains very few data 
points that are far apart so that interpolation between them makes no sense 


— Type 2 is also rarely used, primarily to package orientation for spinning 
spacecraft 


» Normally the input for making Type 2 CKs should contain two times and 
the angular rate in each record 


— Type 3 is the most commonly used type because it provides interpolation 
between the orientation data points stored in the CK 
¢ Interpolation intervals are determined based on the threshold 
value specified in the MAXIMUM_VALID_INTERVAL keyword 
— The threshold interval is specified in units of seconds 
— A Type 3 CK will allow interpolation between all input points for which the 
duration between points is less than or equal to the threshold 
¢ An additional transformation to be combined with the input 
attitude may be specified using OFFSET_ROTATION_* keywords 


— The convention for specification of the offset rotation angles is the same as 
for the input Euler angles 


— A vector defined in the base frame is first multiplied by the offset rotation 
Vinst = [ROTinput] * [ROToffset] * Vref 
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MSOPCK - Output Details (2) 
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The time tags may be adjusted by a constant value, specified 
in seconds, using the TIME_CORRECTION keyword 


The order of input time tags can be checked using the 
CHECK_TIME_ORDER keyword. 


The output CK file contains one or more CK segments 


— Multiple segments are generated if the input data volume is large and 
does not fit into the program’s internal buffer (100,000 pointing records) 


— When the output file has many segments, each segment’s start time is 
equal to the stop time of the previous segment, i.e. there are no gaps at 
the segment boundaries 

The Comment area of the output CK contains the following 
information: 


— Contents of a comment file, if it was specified using the 
COMMENT_FILE_NAME keyword 


— Contents of the setup file 


— Summary of coverage for each segment written to the file, including a 
table listing interpolation intervals for segments of Type 2 or 3 
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MSOPCK - Example (1) 
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Terminal Window 


$ more msopck_setup.example 


MSOPCK setup for predict M'01 CK generation. 


\begindata 

PRODUCER ID 'NAIF/JPL' 

LSK FILE NAME 'naif0007.tls' 

SCLK FILE NAME ORE]  SCLRSCET .U000] tse’ 

COMMENTS FILE NAME "msopck comments.example' 
INTERNAL FILE NAME "sample MO1 SC Orientation CK File' 
CK SEGMENT ID "SAMPLE MO1l SC BUS ATTITUDE' 
INSTRUMENT ID -53000 
REFERENCE FRAME NAME "MARSTAU' 
CK_TYPE 
MAXIMUM VALID INTERVAL 0 
INPUT TIME TYPE SCLK' 
INPUT DATA TYPE "MSOP QUATERNIONS' 
QUATERNION NORM ERROR 1.0E-3 
ANGULAR RATE PRESENT "MAKE UP! 


\begintext 
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MSOPCK - Example (2) 
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Terminal Window 


$ more msopck_comments.example 


Sample Mars Surveyor '01 Orbiter Spacecraft Orientation CK File 


Orientation Data in the File 


This file contains sample orientation for the Mars Surveyor ‘01 
Orbiter (M01) spacecraft frame, 'MO1 SPACECRAFT', relative 

to the Mars Mean Equator and IAU vector of J2000, 'MARSTAU', inertial 
frame, The NAIF 1D cede for the “MOL SPACECRAFT’ frame 16 -=-35000. 


This file is a special sample C-Kernel file created by NAIF to illustrate 
MSOPCK program. This file should not be used for any other purposes. 
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1368.0604 
1372.114 
1373.5 
1374. 
1380. 
1386. 
1392. 
1398. 
1404. 
1404. 
1405. 


MSOPCK - Example (3) 
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msopck_ input 


NO 
NW D BS 
BP BP DN 


CO 3 “OO 1 


Oy 
Bd 


oO Oo 


OO OO OO OO OO OD OO OO OO OO WHO 


.example 


So © © ©} Cc). Co. 1 © iS > Oo Oo © 


CGM 1S 


> 


C 


~-24376335 
24249471 
~-24204185 
-24194814 
-24012676 
~ 23830473 
-23648008 
-23465389 
~ 23282999 
~23277293 
~23231585 
-23100059 
22917393 
~22734161 
~-22551078 
~-22367453 
~-22300583 
~22251770 


oOo CO ODO OO Oo OO OO iG GD AG: 1 [So a, Se Sa SE 


[oe Tees Se a 


> 


C 


- 68291384 
- 68338563 
- 68355329 
- 68358228 
- 68424169 
- 68489895 
-68555126 
- 68620253 
- 68684150 
- 68686688 
-68702790 
.68748174 
-68811325 
.68874177 
- 68936246 
- 68998299 
-69021050 
-69037871 


Terminal Window 


oOo CO ODO OO (o> ae SS ee a | Co OG "OD + CO SS 


C (S "Oo 


> 


-28475901 
-28591829 
-28633291 
-28641744 
~28807922 
-28973563 
-29139303 
~29304524 
-29470173 
~29475362 
-29516507 
-29634561 
-29799308 
-29963482 
- 30128030 
~30291779 
- 30351804 


\é 


.30395477 


Co Oe ae ae > a | Oo Wm Oo © (> ae 2? ae SD) 


CC > 


> 


C 


6 
.6 
6 
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- 62699316 
- 62644323 
-62624605 
-62621196 
- 62543010 
- 62464193 
- 62384833 
-62304745 
~62224580 
~62221455 
-62201253 
-62143935 
-62062853 
-61981412 


1899473 
1816987 
1786298 
1763631 


MSOPCK - Example (4) 
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Terminal Window 


S msopck msopck_setup.example msopck_input.example msopck_example ck.bc 
MSOPCK Utility Program, Version 3.0.0, 2003-05-05; SPICE Toolkit Ver. NOO57 
<comment file contents> 


<setup file contents> 


KEKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKK KKK KKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKK 


RUN-TIME OBTAINED META INFORMATION: 


KEKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKK KKK KK KKKKKKKKKKKKKKKKKKKKKKKKKKKKKK 


PRODUCT CREATION TIME 2004-04-29T12:17:55 
START TIME 2004-04-27T00:00:05.516 
STOP _TIME 2004-04-277T23:59:56.275 


KAEKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKK KKK KK KK KKK KKKKKKKKKKKKKKKKKKKKKKKKKKKKKK 


Cr) 
U 
r) 
U 


INTERPOLATION INTERVALS IN THE FILE SEGMENTS: 


KKEKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKK KKK KK KKK KKK KKK KKKKKKKKKKKKKKKKKKKKKKKKKHK 


SEG.SUMMARY: ID -53000, COVERG: 2004-04-27T00:00:05.516 2004-04-277T23:59:56.275 


2004-04-27T00:00:05.516 2004-04-27T20:05:26.282 
2004-04-27T20:11:20.278 2004-04-27T23:59:56.273 
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NAIE> PREDICKT 
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¢ prediCkt makes CK files from a set of orientation 
specification rules, and schedules defining when these 
rules are to be followed 


¢ prediCkt has a simple command line interface 


¢ prediCkt requires orientation and schedule specifications to 
be provided in a setup file that follows the SPICE text kernel 
syntax 


¢ prediCkt requires the names of all supporting kernels -- 
SPK, PCK, etc -- be provided in a meta-kernel (a “furnsh 
kernel”) 


¢ prediCkt and its User Guide are available only from the 
Utilities link of the NAIF webpages 
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NAIE> PREDICKT - Usage 
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¢ prediCkt has the following command line arguments 
-furnish support data 
-spec ck specs 
-ck outfile 
-tol fit_tolerance [units] 
-<sclk|newsclk> sclk_kernel 
¢ ‘-furnish’, ‘-spec’ and ‘-ck’ are used to specify the input meta- 
kernel, input attitude specification file and output CK file 


¢ ‘-tol’ is used to specify the tolerance to which the orientation 
stored in the CK should match the specified attitude profile 


¢ ‘-sclk’ or ‘-newsclk’ specify the name of an existing SCLK or 
the new “fake” SCLK to be created for use with the output CK 
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NAIE> PREDICKT - Furnsh and Spec Files 
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A “FURNSH” kernel lists SPICE kernels that are 
to be used by prediCkt to determine geometry 
needed to compute orientations 


A prediCkt attitude specification (spec) file, 
using the text kernel syntax, is used to provide 
three types of information: 

— specification of dynamic directions 

— specification of orientations based on these directions 


— specification of the schedules defining when those 
orientations should be followed 


The contents of the FURNSH kernel and the spec 
file are included in the comment area of the 
output CK file 
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PREDICKT - Directions 
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¢ Dynamic directions can be of the following types 


Based on ephemeris (position vectors, velocity vectors) 


Fixed with respect to a reference frame (expressed as a Cartesian vector 
or specified by RA and DEC) 


Towards sub-observer point 
Based on the surface normal and lines of constant latitude or longitude 


Based on other, already defined directions (rotated from them, 
computed as cross products using them, etc) 


¢ Example: these two sets of keyword assignments specify 
nadir and spacecraft velocity directions for the M01 


spacecraft 
DIRECTION SPECS += ( 'ToMars = POSITION OF MARS -' ) 
DIRECTION SPECS += ( "FROM MO1 ="! ) 
DIRECTION SPECS += ( "CORRECTION NONE' ) 
DIRECTION SPECS += ( 'scVelocity = VELOCITY OF M01 -' ) 
DIRECTION SPECS += ( "FROM MARS -' ) 
DIRECTION SPECS += ( "CORRECTION NONE' ) 
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PREDICKT - Orientations 


Navigation and Ancillary Information Facility 


¢ An orientation is specified by: 


— defining that one of the frame’s axes (+X,+Y,+Z,-X,-Y,-Z) points 
exactly along one of the defined directions 


— defining that another of the frame’s axes points as closely as 
possible to another defined direction 


» The third axis is the cross product of the first two 


— specifying the base frame with respect to which the orientation of 
this “constructed” frame is to be computed 


¢ Example: these keyword assignments specify the 
nominal nadir orientation for the THEMIS 
instrument, flown on the M01 spacecraft 


ORIENTATION NAME += 'CameratoMars' 
PRIMARY += '+Z = ToMars' 
SECONDARY += '+Y = scVelocity' 


BASE FRAME += 'J2000' 


Making a CK File 
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PREDICKT - Schedules (1) 
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¢ Aschedule is defined by specifying a series of time 
intervals during which a given orientation is to be 


followed 


— For each interval for a given CK ID, the spec file defines the 
orientation name, start time, and stop time (as Ephemeris Times) 


¢ Example: these spec file keyword assignments 
specify a schedule with a single window during which 
M01 (Mars Odyssey) will yield nadir-pointed 
orientation for the THEMIS instrument 


CK-SCLK = 
CK-SPK = 
CK-FRAMES += 
CK-53000ORIENTATION += 
CK-53000START += 
CK-53000STOP += 
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53 

=53 

-53000 

"SOLUTION TO MO1 THEMIS IR = CameratoMars' 
@2004-FEB-10-00:00 

@2004-FEB-15-00:00 
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PREDICKT - Schedules (2) 
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¢ In the example on the previous slide: 


Making a CK File 


the CK-FRAMES keyword specifies the CK ID to be used in the output CK 


» This ID is incorporated into the keywords defining the schedule 
intervals 


the CK-SCLK keyword specifies the ID of the SCLK kernel to be used in 
creating the CK 


the CK-SPK keyword specifies the ID of the object, the position of which 
is used in applying light time correction when orientation is computed 


the “SOLUTION TO” construct specifies that although the orientation is 
sought for the M01 spacecraft frame (ID -53000), it is computed for the 
camera frame (M01_THEMIS_IR) and then transformed to the spacecraft 
frame 
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PREDICKT - Example (1) 
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S cat m01_map_nadir.prediCkt 


\begindata 


DIRECTION SPECS 
DIRECTION SPECS 
DIRECTION SPECS 


DIRECTION SPECS 
DIRECTION SPECS 
DIRECTION SPECS 


ORIENTATION NAME 
PRIMARY 
SECONDARY 

BASE FRAME 


CK-SCLK 

CK-SPK 

CK-FRAMES 
CK-53000ORIENTATION 
CK-53000START 
CK-53000STOP 

t 


Terminal Window 


POSITION OF MARS -'! 
"FROM MO1 =o 


"CORRECT 


"scVelocity VELOCITY OF M 
"FROM MARS 


ION NONE' 


"CORRECTION NONE' 


"CameratoMars' 


'+Z = ToMars' 


"+Y = scVelocity' 
"J2000' 


53 
-53 
-53000 


"SOLUTION TO M01 THEMIS IR = CameratoMars' 


@2004-FEB-10-00:00 
@2004-FEB-15-00:00 
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PREDICKT - Example (2) 
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Terminal Window 


$ cat m01_map nadir.furnsh 

\begindata 

KERNELS TO LOAD marrdaoT rls" 
"m01 v26.tf' 
"mar033-5.bsp' 
"m01 map rec.bsp' 
‘mOl.tsc' ) 


\begintext 


$ prediCkt -furnish m01_map nadir.furnsh -spec m01_map nadir.prediCkt -ck m01_map_nadir.be -tol 
0.01 degrees -sclk m01.tsc 


Begin Segment: 1 --- SOLUTION TO M01 THEMIS IR = CameratoMars 


Constructing Segment 
From: 2004 FEB 10 00:00:00.000 
To : 2004 FEB 15 00:00:00.000 


Percentage finished: 0.0% 


Percentage finished: 5.0 % (50 quaternions) 


Percentage finished: 95.0 % (925 quaternions) 
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